Version: 1.3.0

Metadata API Documentation

Metadata Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/metadata/api/v1/metadata
Summary: Create a new metadata in the repository

Description

This endpoint creates a new metadata entry in the metadata repository. The metadata can be of different types (KVP, TAG, TAXONOMY) with configurable value types (select, text, datetime, number) for KVP type metadata.

Request

Content-Type: application/json
Authorization: Bearer token required

Payload

Parameter	Description	Data Type	Allowed Values	Required
metadata_id	Unique identifier for the metadata	String	UUID format	No
code	Metadata code	String		No
title	Title of the metadata	String	Non-empty string	Yes
description	Description of the metadata	String		No
type	Type of metadata	String	KVP, TAG, TAXONOMY	Yes
value_type	Type of value (required for KVP type)	String	select, text, datetime, number	Yes (for KVP)
values	List of possible values	Array[String]		No
metadata	Additional metadata configuration	Object	e.g., {"length": 100, "date_format":"YY"}	No
is_active	Activation status	Boolean	true/false	No
created_by_name	Name of the creator	String		No

Response

{
  "status_code": 200,
  "message": "Successfully created",
  "data": {
    "metadata_id": "uuid-string",
    "title": "Metadata Title",
    "code": "metadata-code",
    "type": "KVP",
    "value_type": "text",
    "created_at": "2025-08-25T10:00:00.000Z",
    "created_by": "user-id"
  }
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/metadata/api/v1/metadata"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "title": "Sample Metadata",
    "description": "This is a sample metadata entry",
    "type": "KVP",
    "value_type": "text",
    "values": ["value1", "value2"],
    "metadata": {
        "length": 100,
        "date_format": "YY"
    },
    "is_active": True
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Metadata Search Endpoint

Method: POST
Path: https://api.kadal.ai/cl/metadata/api/v1/metadata/search
Summary: List or search metadata in the repository

Description

This endpoint allows searching and listing metadata entries with various filtering options. It supports both regular text search and semantic search capabilities.

Request

Content-Type: application/json
Authorization: Bearer token required

Query Parameters

Parameter	Description	Data Type	Default	Required
page_no	Page number for pagination	Integer	0	No
page_size	Number of items per page	Integer	100	No
is_search_on_value	Enable search in metadata values	Boolean	true	No
semantic_search	Enable semantic search capability	Boolean	false	No
ext_user_id_ref	External user ID reference	String		No

Payload

Parameter	Description	Data Type	Allowed Values	Required
type	Type of metadata to search	String	KVP, TAG, TAXONOMY	Yes
search_text	Text to search for	String		No
is_active	Filter by activation status	Boolean		No
metadata_ids	List of specific metadata IDs	Array[String]		No

Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "total_count": 10,
    "items": [
      {
        "metadata_id": "uuid-string",
        "title": "Metadata Title",
        "code": "metadata-code",
        "type": "KVP",
        "value_type": "text",
        "created_at": "2025-08-25T10:00:00.000Z",
        "created_by": "user-id",
        "is_active": true,
        "values": ["value1", "value2"]
      }
    ]
  }
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/metadata/api/v1/metadata/search"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Query parameters
params = {
    "page_no": 0,
    "page_size": 10,
    "semantic_search": True,
    "is_search_on_value": True
}

# Search payload
data = {
    "type": "KVP",
    "search_text": "sample search",
    "is_active": True
}

# Make the POST request
response = requests.post(url, headers=headers, params=params, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Metadata Similar Search Endpoint

Method: POST
Path: https://api.kadal.ai/cl/metadata/api/v1/metadata/similar-search
Summary: Semantic similarity search on metadata

Description

This endpoint performs semantic similarity search using vector embeddings to find similar content. It supports:

Vector embeddings for semantic search
Type="STATEMENT" for searching statements
Type="KVP" for searching within Key-Value pairs metadata
Type="STATEMENT_TYPE" for searching statements and retrieving associated Statement_Types

Request

Content-Type: application/json
Authorization: Bearer token required

Query Parameters

Parameter	Description	Data Type	Default	Required
page_no	Page number for pagination	Integer	0	No
page_size	Number of items per page	Integer	100	No
min_relevant_score	Minimum similarity score threshold	Float	0.7	No
sorting_by	Field to sort results by	String	"score"	No
order	Sort order (asc/desc)	String	"desc"	No
is_search_on_value	Enable search in values	Boolean	true	No

Payload
Parameter Description Data Type Allowed Values Required
type Type of metadata to search String KVP, STATEMENT, STATEMENT_TYPE Yes
title Search text for similarity matching String Yes

Parameter	Description	Data Type	Allowed Values	Required
type	Type of metadata to search	String	KVP, STATEMENT, STATEMENT_TYPE	Yes
title	Search text for similarity matching	String		Yes

Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "total_count": 5,
    "items": [
      {
        "metadata_id": "uuid-string",
        "title": "Similar Metadata",
        "type": "KVP",
        "similarity_score": 0.85,
        "created_at": "2025-08-25T10:00:00.000Z"
      }
    ]
  }
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/metadata/api/v1/metadata/similar-search"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Query parameters
params = {
    "page_no": 0,
    "page_size": 10,
    "min_relevant_score": 0.8,
    "sorting_by": "score",
    "order": "desc"
}

# Search payload
data = {
    "type": "KVP",
    "title": "search text for similarity matching"
}

# Make the POST request
response = requests.post(url, headers=headers, params=params, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Metadata Deletion Endpoint

Method: DELETE
Path: https://api.kadal.ai/cl/metadata/api/v1/metadata
Summary: Delete single or bulk metadata

Description

This endpoint allows deletion of one or multiple metadata entries from the repository.

Request

Content-Type: application/json
Authorization: Bearer token required
Query Parameters
Parameter Description Data Type Required
ext_user_id_ref External user ID reference String No
Payload
Parameter Description Data Type Required
metadata_ids List of metadata IDs to delete Array[String] Yes

Parameter	Description	Data Type	Required
ext_user_id_ref	External user ID reference	String	No

Parameter	Description	Data Type	Required
metadata_ids	List of metadata IDs to delete	Array[String]	Yes

Response

{
  "status_code": 200,
  "message": "Successfully deleted metadata",
  "data": {
    "deleted_count": 2,
    "metadata_ids": ["uuid1", "uuid2"]
  }
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/metadata/api/v1/metadata"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "metadata_ids": ["uuid1", "uuid2"]
}

# Make the DELETE request
response = requests.delete(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Metadata Usage Count Endpoint

Method: POST
Path: https://api.kadal.ai/cl/metadata/api/v1/metadata/usage-count
Summary: Get usage count of specific metadata

Description

This endpoint returns the usage count of specified metadata entries.

Request

Content-Type: application/json
Authorization: Bearer token required
Query Parameters
Parameter Description Data Type Required
ext_user_id_ref External user ID reference String No
Payload
Parameter Description Data Type Required
metadata_ids List of metadata IDs Array[String] Yes

Parameter	Description	Data Type	Required
ext_user_id_ref	External user ID reference	String	No

Parameter	Description	Data Type	Required
metadata_ids	List of metadata IDs	Array[String]	Yes

Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "usage_counts": [
      {
        "metadata_id": "uuid1",
        "count": 5
      },
      {
        "metadata_id": "uuid2",
        "count": 3
      }
    ]
  }
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/metadata/api/v1/metadata/usage-count"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "metadata_ids": ["uuid1", "uuid2"]
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

Statement Management Endpoint

1. Statement Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/metadata/api/v1/statement
Summary: Create a new statement, root taxonomy, or taxonomy nodes

Description

This endpoint creates new statements or taxonomy nodes in the repository. It supports:

Creating root taxonomy nodes (Type=CFDOCUMENT, iscfitem=False)
Creating taxonomy child nodes (Type=Any, iscfitem=True)
Creating statements (Type=Any, iscfitem=False)
Creating KVP properties (Type=KVP)

Supported Relationship Types:

isPeerOf: Indicates peer relationship
isPartOf: Indicates part-whole relationship
exactMatchOf: Indicates exact matching content
precedes: Indicates sequential order
isRelatedTo: Indicates general relationship
replacedBy: Indicates replacement relationship
hasSkillLevel: Indicates skill level relationship

Request

Content-Type: application/json
Authorization: Bearer token required
Query Parameters
Parameter Description Data Type Required
ext_user_id_ref External user ID reference String No

Parameter	Description	Data Type	Required
ext_user_id_ref	External user ID reference	String	No

Payload

Parameter	Description	Data Type	Allowed Values	Required
title	Statement title	String		Yes
type	Type of statement	String	CFDOCUMENT, KVP, OTHER	Yes
description	Statement description	String		No
iscfitem	Whether it's a taxonomy node	Boolean	true/false	No
metadata_template_id	Template ID	String	UUID format	No
origin_id	Parent node ID	String	UUID format	No
metadata	Additional metadata	Object		No
taxonomy	Taxonomy relationships	Array	Array of relationship objects	No

Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "metadata_id": "uuid-string",
    "title": "Statement Title",
    "type": "CFDOCUMENT",
    "iscfitem": false,
    "created_at": "2025-08-25T10:00:00.000Z",
    "created_by": "user-id"
  }
}

Usage

import requests

# Define the API endpoint and the payload
url = "https://api.kadal.ai/cl/metadata/api/v1/statement"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Create a root taxonomy node
data = {
    "title": "Mathematics",
    "type": "CFDOCUMENT",
    "description": "Root taxonomy for mathematics",
    "iscfitem": False
}

# Create a taxonomy child node
data_child = {
    "title": "Algebra",
    "type": "OTHER",
    "description": "Algebra concepts",
    "iscfitem": True,
    "origin_id": "parent-uuid",
    "taxonomy": [
        {
            "metadata_template_id": "template-uuid",
            "relationship_type": "isPartOf"
        }
    ]
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

2. Statement Update Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/metadata/api/v1/statement/{metadata_id}
Summary: Update a statement or taxonomy node

Description

This endpoint updates existing statements or taxonomy nodes. It can also be used to:

Update basic statement/taxonomy information
Modify taxonomy relationships
Associate taxonomy/statement/KVP relationships

Request

Content-Type: application/json
Authorization: Bearer token required
Path Parameters
Parameter Description Data Type Required
metadata_id ID of statement to update String (UUID) Yes
Query Parameters
Parameter Description Data Type Required
ext_user_id_ref External user ID reference String No

Parameter	Description	Data Type	Required
metadata_id	ID of statement to update	String (UUID)	Yes

Parameter	Description	Data Type	Required
ext_user_id_ref	External user ID reference	String	No

Payload

Parameter	Description	Data Type	Allowed Values	Required
title	New statement title	String		No
description	New description	String		No
metadata	Updated metadata	Object		No
taxonomy	Updated relationships	Array	Array of relationship objects	No

Response

{
  "status_code": 200,
  "message": "Successfully updated",
  "data": {
    "metadata_id": "uuid-string",
    "title": "Updated Statement",
    "type": "CFDOCUMENT",
    "updated_at": "2025-08-25T10:00:00.000Z",
    "updated_by": "user-id"
  }
}

Usage

import requests

# Define the API endpoint and the payload
metadata_id = "your-statement-uuid"
url = f"https://api.kadal.ai/cl/metadata/api/v1/statement/{metadata_id}"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Update statement data
data = {
    "title": "Updated Mathematics",
    "description": "Updated taxonomy for mathematics",
    "taxonomy": [
        {
            "metadata_template_id": "template-uuid",
            "relationship_type": "isPartOf"
        }
    ]
}

# Make the PUT request
response = requests.put(url, headers=headers, json=data)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

3. Statement Relationships Retrieval Endpoint

Method: GET
Path: https://api.kadal.ai/cl/metadata/api/v1/statement/{metadata_id}/{relationship_type}
Summary: Get all related items of a taxonomy node by relationship type

Description

This endpoint retrieves all related items (statements, nodes) of a taxonomy node based on the specified relationship type. Currently supports forward relationships (child nodes).

Request

Content-Type: application/json
Authorization: Bearer token required
Path Parameters
Parameter Description Data Type Required
metadata_id Statement/Node ID String (UUID) Yes
relationship_type Type of relationship String Yes

Parameter	Description	Data Type	Required
metadata_id	Statement/Node ID	String (UUID)	Yes
relationship_type	Type of relationship	String	Yes

Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "items": [
      {
        "metadata_id": "child-uuid",
        "title": "Child Node",
        "type": "OTHER",
        "relationship_type": "isPartOf",
        "created_at": "2025-08-25T10:00:00.000Z"
      }
    ]
  }
}

Usage

import requests

# Define the API endpoint
metadata_id = "your-node-uuid"
relationship_type = "isPartOf"
url = f"https://api.kadal.ai/cl/metadata/api/v1/statement/{metadata_id}/{relationship_type}"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

# Make the GET request
response = requests.get(url, headers=headers)

# Print the response
if response.status_code == 200:
    print("Response Data:", response.json())
else:
    print("Failed to call the API. Status Code:", response.status_code)
    print("Response Text:", response.text)

4. Statement Relationship Count Endpoint

Method: GET
Path: /statement/{metadata_id}/{relationship_type}/count
Summary: Get count of relationships for a taxonomy node

Description

This endpoint returns the count of relationships of a specific type for a given taxonomy node.

Request

Authorization: Bearer token required
Path Parameters
Parameter Description Data Type Required
metadata_id Statement/Node ID String (UUID) Yes
relationship_type Type of relationship String Yes

Parameter	Description	Data Type	Required
metadata_id	Statement/Node ID	String (UUID)	Yes
relationship_type	Type of relationship	String	Yes

Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "count": 5
  }
}

Usage

import requests

metadata_id = "your-node-uuid"
relationship_type = "isPartOf"
url = f"https://api.kadal.ai/cl/metadata/api/v1/statement/{metadata_id}/{relationship_type}/count"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(url, headers=headers)
print(response.json())

5. Taxonomy Import Endpoint

Method: POST
Path: /taxonomy/import/json
Summary: Import taxonomy from JSON

Description

This endpoint allows importing taxonomy structure from a JSON file.

Request

Content-Type: application/json
Authorization: Bearer token required
Payload
Parameter Description Data Type Required
taxonomy_data Taxonomy structure Object Yes

Parameter	Description	Data Type	Required
taxonomy_data	Taxonomy structure	Object	Yes

Response

{
  "status_code": 200,
  "message": "Successfully imported taxonomy",
  "data": {
    "imported_count": 10,
    "root_node_id": "uuid-string"
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/metadata/api/v1/taxonomy/import/json"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "taxonomy_data": {
        "title": "Root Node",
        "children": [
            {
                "title": "Child Node 1"
            }
        ]
    }
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

6. Statement Associations Endpoint

Method: POST
Path: /statement-associations/{metadata_id}
Summary: Get all items with forward/backward relationships

Description

Get all items/nodes/statements of a taxonomy node by relationship type with directional support:

forward: retrieves all child nodes
backward: retrieves all other nodes including parent node
both: retrieves all related nodes

Request

Content-Type: application/json
Authorization: Bearer token required
Path Parameters
Parameter Description Data Type Required
metadata_id Statement/Node ID String (UUID) Yes
Payload
Parameter Description Data Type Allowed Values Required
direction Relationship direction String forward, backward, both Yes
relationship_type Type of relationship String isPartOf, isPeerOf, etc. Yes

Parameter	Description	Data Type	Required
metadata_id	Statement/Node ID	String (UUID)	Yes

Parameter	Description	Data Type	Allowed Values	Required
direction	Relationship direction	String	forward, backward, both	Yes
relationship_type	Type of relationship	String	isPartOf, isPeerOf, etc.	Yes

Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "items": [
      {
        "metadata_id": "uuid-string",
        "title": "Node Title",
        "type": "OTHER",
        "relationship_type": "isPartOf",
        "direction": "forward"
      }
    ]
  }
}

Usage

import requests

metadata_id = "your-node-uuid"
url = f"https://api.kadal.ai/cl/metadata/api/v1/statement-associations/{metadata_id}"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "direction": "both",
    "relationship_type": "isPartOf"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

7. Bulk KVP Metatdata Creation Endpoint

Method: POST
Path: /metadata/bulk-kvp
Summary: Create multiple KVP metadata entries in bulk

Description

Creates multiple KVP metadata entries if they don't exist. Maximum limit is 2000 entries per request.

Request

Content-Type: application/json
Authorization: Bearer token required
Query Parameters
Parameter Description Data Type Required
ext_user_id_ref External user ID reference String No
Payload
Parameter Description Data Type Required
metadata_list List of metadata entries Array[Object] Yes

Parameter	Description	Data Type	Required
ext_user_id_ref	External user ID reference	String	No

Parameter	Description	Data Type	Required
metadata_list	List of metadata entries	Array[Object]	Yes

Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "created_count": 2,
    "metadata_ids": ["uuid1", "uuid2"]
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/metadata/api/v1/metadata/bulk-kvp"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "metadata_list": [
        {
            "title": "KVP 1",
            "type": "KVP",
            "value_type": "text",
            "values": ["value1"]
        },
        {
            "title": "KVP 2",
            "type": "KVP",
            "value_type": "number"
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

8. Utility Search Endpoint

Method: POST
Path: /metadata/utility-search
Summary: List/Search API for Statement-Type, Taxonomy, KVP

Description

This endpoint provides a unified search across different types of metadata: Statement-Type, Taxonomy, and KVP.

Request

Content-Type: application/json
Authorization: Bearer token required
Query Parameters
Parameter Description Data Type Required
ext_user_id_ref External user ID reference String No
Payload
Parameter Description Data Type Required
type Types to search Array[String] Yes
search_text Search query String No

Parameter	Description	Data Type	Required
ext_user_id_ref	External user ID reference	String	No

Parameter	Description	Data Type	Required
type	Types to search	Array[String]	Yes
search_text	Search query	String	No

Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "statement_types": [...],
    "taxonomies": [...],
    "kvp_items": [...]
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/metadata/api/v1/metadata/utility-search"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "type": ["STATEMENT_TYPE", "TAXONOMY", "KVP"],
    "search_text": "search query"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Taxonomy Category Management V1 Endpoints

Category Upsert Endpoint

Method: POST
Path: https://api.kadal.ai/cl/metadata/api/v1/category
Summary: Create or update taxonomy category

Description

Creates or updates a taxonomy category in the metadata repository.

Request

Content-Type: application/json
Authorization: Bearer token required
Query Parameters
Parameter Description Data Type Required
ext_user_id_ref External user ID reference String No
Payload
Parameter Description Data Type Required
title Category title String Yes
description Category description String No
metadata Additional metadata Object No

Parameter	Description	Data Type	Required
ext_user_id_ref	External user ID reference	String	No

Parameter	Description	Data Type	Required
title	Category title	String	Yes
description	Category description	String	No
metadata	Additional metadata	Object	No

Response

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "category_id": "uuid-string",
    "title": "Category Title",
    "description": "Category Description",
    "created_at": "2025-08-25T10:00:00.000Z"
  }
}

Usage

import requests

url = "https://api.kadal.ai/cl/metadata/api/v1/category"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "title": "New Category",
    "description": "A new taxonomy category"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Metadata Template Management V1 Endpoints

1. Metadata Template Creation Endpoint

Method: POST
Path: https://api.kadal.ai/cl/metadata/api/v1/metadata-template
Summary: Create a new metadata template or statement type

Description

Creates a new metadata template or statement type in the repository. Supports relationship types like isPeerOf, isPartOf, exactMatchOf, precedes, isRelatedTo, replacedBy, and hasSkillLevel.

Request

Content-Type: application/json
Authorization: Bearer token required
Query Parameters
Parameter Description Data Type Required
ext_user_id_ref External user ID reference String No

Parameter	Description	Data Type	Required
ext_user_id_ref	External user ID reference	String	No

Payload

Parameter	Description	Data Type	Required
title	Template title (must not be empty)	String	Yes
catagory	Category for the template	String	No
keys	List of key configurations	Array[Object]	No
mapped_objects_types	List of object types that can be mapped	Array[String]	No
mapped_item_types	List of item type mappings	Array[Object]	No
metadata	Additional metadata configuration	Object	No
is_active	Activation status	Boolean	No

Keys Object Structure

Parameter	Description	Data Type	Required
metadata_id	Key metadata ID	String	No
version_id	Key version ID	String	No
key	Key name	String	No
type	Key type	String	No

Mapped Item Types Object Structure

Parameter	Description	Data Type	Required
metadata_template_id	Template ID	String	No
title	Title	String	No
version_id	Version ID	String	No
relationship_type	Type of relationship	String	No

Example Request

{
  "title": "Sample Template",
  "catagory": "Documentation",
  "keys": [
    {
      "metadata_id": "123",
      "key": "author",
      "type": "text"
    }
  ],
  "mapped_objects_types": ["document", "image"],
  "metadata": {
    "length": 100,
    "date_format": "YY"
  },
  "is_active": true
}

Response

{
  "status": "200",
  "message": "Successfully created",
  "data": [
    {
      "metadata_template_id": "uuid-string",
      "title": "Sample Template",
      "catagory": "Documentation",
      "keys": [
        {
          "metadata_id": "123",
          "key": "author",
          "type": "text"
        }
      ],
      "created_at": "2025-08-25T10:00:00.000Z",
      "created_by": "user-id"
    }
  ]
}

Error Responses

{
  "status": "400",
  "message": "Bad Request : Invalid argument error"
}

{
  "status": "404",
  "message": "Item not found"
}

{
  "status": "500",
  "message": "Internal server error"
}

{
  "status": "422",
  "message": "Validation Error",
  "detail": [
    {
      "loc": ["body", "title"],
      "msg": "Title must not be empty",
      "type": "value_error"
    }
  ]
}

2. Metadata Template Update Endpoint

Method: PUT
Path: https://api.kadal.ai/cl/metadata/api/v1/metadata-template/{metadata_template_id}
Summary: Edit an existing metadata template or statement type

Description

Updates an existing metadata template or statement type. Supports modifying title, keys, mapped types, and metadata configuration.

Supports relationship types:

isPeerOf
isPartOf
exactMatchOf
precedes
isRelatedTo
replacedBy
hasSkillLevel

Request

Content-Type: application/json
Authorization: Bearer token required
Path Parameters
Parameter Description Data Type Required
metadata_template_id Template ID to update String (UUID) Yes
Query Parameters
Parameter Description Data Type Required
ext_user_id_ref External user ID reference String No
Payload
All fields are optional. Only include fields that need to be updated.

Parameter	Description	Data Type	Required
metadata_template_id	Template ID to update	String (UUID)	Yes

Parameter	Description	Data Type	Required
ext_user_id_ref	External user ID reference	String	No

Parameter	Description	Data Type	Required
title	New template title (must not be empty if provided)	String	No
catagory	New category	String	No
keys	Updated key configurations	Array[Object]	No
mapped_objects_types	Updated list of mapped object types	Array[String]	No
mapped_item_types	Updated list of item type mappings	Array[Object]	No
metadata	Updated metadata configuration	Object	No
is_active	New activation status	Boolean	No

Example Request

{
  "title": "Updated Template",
  "metadata": {
    "length": 200,
    "date_format": "YYYY"
  },
  "keys": [
    {
      "metadata_id": "123",
      "key": "author",
      "type": "text"
    },
    {
      "metadata_id": "125",
      "key": "category",
      "type": "select"
    }
  ]
}

Response

{
  "status": "200",
  "message": "Successfully updated",
  "data": [
    {
      "metadata_template_id": "uuid-string",
      "title": "Updated Template",
      "updated_at": "2025-08-25T10:00:00.000Z",
      "updated_by": "user-id"
    }
  ]
}

Error Responses

{
  "status": "400",
  "message": "Bad Request : Invalid argument error"
}

{
  "status": "404",
  "message": "Template not found"
}

{
  "status": "500",
  "message": "Internal server error"
}

{
  "status": "422",
  "message": "Validation Error",
  "detail": [
    {
      "loc": ["body", "title"],
      "msg": "Title must not be empty",
      "type": "value_error"
    }
  ]
}

Usage

import requests

def create_template():
    url = "https://api.kadal.ai/cl/metadata/api/v1/metadata-template"
    token = "your_token_here"

    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }

    # Example template for a document metadata
    data = {
        "title": "Document Metadata Template",
        "catagory": "Documentation",
        "keys": [
            {
                "metadata_id": "123",
                "key": "author",
                "type": "text"
            },
            {
                "metadata_id": "124",
                "key": "publish_date",
                "type": "datetime"
            }
        ],
        "mapped_objects_types": ["document", "pdf"],
        "mapped_item_types": [
            {
                "metadata_template_id": "template-uuid",
                "title": "Related Template",
                "relationship_type": "isRelatedTo"
            }
        ],
        "metadata": {
            "length": 100,
            "date_format": "YY",
            "validation_rules": {
                "author": "required"
            }
        },
        "is_active": true
    }

    response = requests.post(url, headers=headers, json=data)
    print("Status Code:", response.status_code)
    print("Response:", response.json())

# Update template
def update_template(metadata_template_id):
    url = f"https://api.kadal.ai/cl/metadata/api/v1/metadata-template/{metadata_template_id}"
    token = "your_token_here"

    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }

    # Only include fields that need to be updated
    data = {
        "title": "Updated Document Template",
        "keys": [
            {
                "metadata_id": "123",
                "key": "author",
                "type": "text"
            },
            {
                "metadata_id": "125",
                "key": "category",
                "type": "select"
            }
        ],
        "metadata": {
            "length": 200,
            "date_format": "YYYY",
            "validation_rules": {
                "author": "required",
                "category": "required"
            }
        }
    }

    response = requests.put(url, headers=headers, json=data)
    print("Status Code:", response.status_code)
    print("Response:", response.json())

Metadata API Documentation

Metadata Creation Endpoint​

Description​

Request​

Payload​

Response​

Usage​

Metadata Search Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Usage​

Metadata Similar Search Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Usage​

Metadata Deletion Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Usage​

Metadata Usage Count Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Usage​

Statement Management Endpoint​

1. Statement Creation Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Usage​

2. Statement Update Endpoint​

Description​

Request​

Path Parameters​

Query Parameters​

Payload​

Response​

Usage​

3. Statement Relationships Retrieval Endpoint​

Description​

Request​

Path Parameters​

Response​

Usage​

4. Statement Relationship Count Endpoint​

Description​

Request​

Path Parameters​

Response​

Usage​

5. Taxonomy Import Endpoint​

Description​

Request​

Payload​

Response​

Usage​

6. Statement Associations Endpoint​

Description​

Request​

Path Parameters​

Payload​

Response​

Usage​

7. Bulk KVP Metatdata Creation Endpoint​

Description​

Request​

Query Parameters​

Metadata Creation Endpoint

Description

Request

Payload

Response

Usage

Metadata Search Endpoint

Description

Request

Query Parameters

Payload

Response

Usage

Metadata Similar Search Endpoint

Description

Request

Query Parameters

Payload

Response

Usage

Metadata Deletion Endpoint

Description

Request

Query Parameters

Payload

Response

Usage

Metadata Usage Count Endpoint

Description

Request

Query Parameters

Payload

Response

Usage

Statement Management Endpoint

1. Statement Creation Endpoint

Description

Request

Query Parameters

Payload

Response

Usage

2. Statement Update Endpoint

Description

Request

Path Parameters

Query Parameters

Payload

Response

Usage

3. Statement Relationships Retrieval Endpoint

Description

Request

Path Parameters

Response

Usage

4. Statement Relationship Count Endpoint

Description

Request

Path Parameters

Response

Usage

5. Taxonomy Import Endpoint

Description

Request

Payload

Response

Usage

6. Statement Associations Endpoint

Description

Request

Path Parameters

Payload

Response

Usage

7. Bulk KVP Metatdata Creation Endpoint

Description

Request

Query Parameters

Payload